home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 7 / Apprentice-Release7.iso / Environments / PowerLisp 2.01 / Supplemental Documentation / Documentation / Chapter 05. Program Structure < prev    next >
Text File  |  1995-03-27  |  60KB  |  1,276 lines
  1. Common Lisp the Language, 2nd Edition
  2. -------------------------------------------------------------------------------
  3.  
  4. 5. Program Structure
  5.  
  6. In chapter 2 the syntax was sketched for notating data objects in Common Lisp.
  7. The same syntax is used for notating programs because all Common Lisp programs
  8. have a representation as Common Lisp data objects.
  9.  
  10. Lisp programs are organized as forms and functions. Forms are evaluated
  11. (relative to some context) to produce values and side effects. Functions are
  12. invoked by applying them to arguments. The most important kind of form performs
  13. a function call; conversely, a function performs computation by evaluating
  14. forms.
  15.  
  16. In this chapter, forms are discussed first and then functions. Finally, certain
  17. ``top level'' special forms are discussed; the most important of these is
  18. defun, whose purpose is to define a named function.
  19.  
  20. -------------------------------------------------------------------------------
  21.  
  22.    *  Forms
  23.         o  Self-Evaluating Forms
  24.         o  Variables
  25.         o  Special Forms
  26.         o  Macros
  27.         o  Function Calls
  28.    *  Functions
  29.         o  Named Functions
  30.         o  Lambda-Expressions
  31.    *  Top-Level Forms
  32.         o  Defining Named Functions
  33.         o  Declaring Global Variables and Named Constants
  34.         o  Control of Time of Evaluation
  35.  
  36. -------------------------------------------------------------------------------
  37.  
  38.  
  39. 5.1. Forms
  40.  
  41. The standard unit of interaction with a Common Lisp implementation is the form,
  42. which is simply a data object meant to be evaluated as a program to produce one
  43. or more values (which are also data objects). One may request evaluation of any
  44. data object, but only certain ones are meaningful. For instance, symbols and
  45. lists are meaningful forms, while arrays normally are not. Examples of
  46. meaningful forms are 3, whose value is 3, and (+ 3 4), whose value is 7. We
  47. write 3 => 3 and (+ 3 4) => 7 to indicate these facts. (=> means ``evaluates
  48. to.'')
  49.  
  50. Meaningful forms may be divided into three categories: self-evaluating forms,
  51. such as numbers; symbols, which stand for variables; and lists. The lists in
  52. turn may be divided into three categories: special forms, macro calls, and
  53. function calls.
  54.  
  55. [old_change_begin]
  56. Any Common Lisp data object not explicitly defined here to be a valid form is
  57. not a valid form. It is an error to evaluate anything but a valid form.
  58.  
  59. -------------------------------------------------------------------------------
  60. Implementation note: An implementation is free to make implementation-dependent
  61. extensions to the evaluator but is strongly encouraged to signal an error on
  62. any attempt to evaluate anything but a valid form or an object for which a
  63. meaningful evaluation extension has been purposely defined.
  64. -------------------------------------------------------------------------------
  65.  
  66. [old_change_end]
  67.  
  68. [change_begin]
  69. X3J13 voted in October 1988 (EVAL-OTHER)   to specify that all standard Common
  70. Lisp data objects other than symbols and lists (including defstruct structures
  71. defined without the :type option) are self-evaluating.
  72. [change_end]
  73.  
  74. -------------------------------------------------------------------------------
  75.  
  76.    *  Self-Evaluating Forms
  77.    *  Variables
  78.    *  Special Forms
  79.    *  Macros
  80.    *  Function Calls
  81.  
  82. -------------------------------------------------------------------------------
  83.  
  84.  
  85. 5.1.1. Self-Evaluating Forms
  86.  
  87. All numbers, characters, strings, and bit-vectors are self-evaluating forms.
  88. When such an object is evaluated, that object (or possibly a copy in the case
  89. of numbers or characters) is returned as the value of the form. The empty list
  90. (), which is also the false value nil, is also a self-evaluating form: the
  91. value of nil is nil. Keywords (symbols written with a leading colon) also
  92. evaluate to themselves: the value of :start is :start.
  93.  
  94. [change_begin]
  95. X3J13 voted in January 1989 (CONSTANT-MODIFICATION)   to clarify that it is an
  96. error to destructively modify any object that appears as a constant in
  97. executable code, whether as a self-evaluating form or within a quote special
  98. form.
  99. [change_end]
  100.  
  101. -------------------------------------------------------------------------------
  102.  
  103. 5.1.2. Variables
  104.  
  105. Symbols are used as names of variables in Common Lisp programs. When a symbol
  106. is evaluated as a form, the value of the variable it names is produced. For
  107. example, after doing (setq items 3), which assigns the value 3 to the variable
  108. named items, then items => 3. Variables can be assigned to, as by setq, or
  109. bound, as by let. Any program construct that binds a variable effectively saves
  110. the old value of the variable and causes it to have a new value, and on exit
  111. from the construct the old value is reinstated.
  112.  
  113. There are actually two kinds of variables in Common Lisp, called lexical (or
  114. static) variables and special (or dynamic) variables. At any given time either
  115. or both kinds of variable with the same name may have a current value. Which of
  116. the two kinds of variable is referred to when a symbol is evaluated depends on
  117. the context of the evaluation. The general rule is that if the symbol occurs
  118. textually within a program construct that creates a binding for a variable of
  119. the same name, then the reference is to the variable specified by the binding;
  120. if no such program construct textually contains the reference, then it is taken
  121. to refer to the special variable of that name.
  122.  
  123. The distinction between the two kinds of variable is one of scope and extent. A
  124. lexically bound variable can be referred to only by forms occurring at any
  125. place textually within the program construct that binds the variable. A
  126. dynamically bound (special) variable can be referred to at any time from the
  127. time the binding is made until the time evaluation of the construct that binds
  128. the variable terminates. Therefore lexical binding of variables imposes a
  129. spatial limitation on occurrences of references (but no temporal limitation,
  130. for the binding continues to exist as long as the possibility of reference
  131. remains). Conversely, dynamic binding of variables imposes a temporal
  132. limitation on occurrences of references (but no spatial limitation). For more
  133. information on scope and extent, see chapter 3.
  134.  
  135. The value a special variable has when there are currently no bindings of that
  136. variable is called the global value of the (special) variable. A global value
  137. can be given to a variable only by assignment, because a value given by binding
  138. is by definition not global.
  139.  
  140. It is possible for a special variable to have no value at all, in which case it
  141. is said to be unbound. By default, every global variable is unbound unless and
  142. until explicitly assigned a value, except for those global variables defined in
  143. this book or by the implementation already to have values when the Lisp system
  144. is first started. It is also possible to establish a binding of a special
  145. variable and then cause that binding to be valueless by using the function
  146. makunbound. In this situation the variable is also said to be ``unbound,''
  147. although this is a misnomer; precisely speaking, it is bound but valueless. It
  148. is an error to refer to a variable that is unbound.
  149.  
  150. [change_begin]
  151. X3J13 voted in June 1989 (UNDEFINED-VARIABLES-AND-FUNCTIONS)   to specify more
  152. precisely the effects of referring to an unbound variable.
  153.  
  154. Reading an unbound variable or an undefined function must be detected in the
  155. highest safety setting (see the safety quality of the optimize declaration
  156. specifier) but the effect is undefined in any other safety setting. That is,
  157. reading an unbound variable should signal an error and reading an undefined
  158. function should signal an error. (``Reading a function'' includes both
  159. references to the function using the function special form, such as f in
  160. (function f), and references to the function in a call, such as f in (f x y).)
  161.  
  162. For the case of inline functions (in implementations where they are supported),
  163. a permitted point of view is that performing the inlining constitutes the read
  164. of the function, so that an fboundp check need not be done at execution time.
  165. Put another way, the effect of the application of fmakunbound to a function
  166. name on potentially inlined references to that function is undefined.
  167.  
  168. When an unbound variable is detected an error of type unbound-variable is
  169. signaled, and the name slot of the unbound-variable condition is initialized to
  170. the name of the offending variable.
  171.  
  172. When an undefined function is detected an error of type undefined-function is
  173. signaled, and the name slot of the undefined-function condition is initialized
  174. to the name of the offending function.
  175.  
  176. The condition type unbound-slot, which inherits from cell-error, has an
  177. additional slot instance, which can be initialized using the :instance keyword
  178. to make-condition. The function unbound-slot-instance accesses this slot.
  179.  
  180. The type of error signaled by the default primary method for the CLOS
  181. slot-unbound generic function is unbound-slot. The instance slot of the
  182. unbound-slot condition is initialized to the offending instance and the name
  183. slot is initialized to the name of the offending variable.
  184. [change_end]
  185.  
  186. Certain global variables are reserved as ``named constants.'' They have a
  187. global value and may not be bound or assigned to. For example, the symbols t
  188. and nil are reserved. One may not assign a value to t or nil, and one may not
  189. bind t or nil. The global value of t is always t, and the global value of nil
  190. is always nil. Constant symbols defined by defconstant also become reserved and
  191. may not be further assigned to or bound (although they may be redefined, if
  192. necessary, by using defconstant again). Keyword symbols, which are notated with
  193. a leading colon, are reserved and may never be assigned to or bound; a keyword
  194. always evaluates to itself.
  195.  
  196. -------------------------------------------------------------------------------
  197.  
  198. 5.1.3. Special Forms
  199.  
  200. If a list is to be evaluated as a form, the first step is to examine the first
  201. element of the list. If the first element is one of the symbols appearing in
  202. table 5-1, then the list is called a special form. (This use of the word
  203. ``special'' is unrelated to its use in the phrase ``special variable.'')
  204.  
  205. Special forms are generally environment and control constructs. Every special
  206. form has its own idiosyncratic syntax. An example is the if special form: (if p
  207. (+ x 4) 5) in Common Lisp means what ``if p then x+4 else 5'' means in Algol.
  208.  
  209. The evaluation of a special form normally produces a value or values, but the
  210. evaluation may instead call for a non-local exit; see return-from, go, and
  211. throw.
  212.  
  213. The set of special forms is fixed in Common Lisp; no way is provided for the
  214. user to define more. The user can create new syntactic constructs, however, by
  215. defining macros.
  216.  
  217. The set of special forms in Common Lisp is purposely kept very small because
  218. any program-analyzing program must have special knowledge about every type of
  219. special form. Such a program needs no special knowledge about macros because it
  220. is simple to expand the macro and operate on the resulting expansion. (This is
  221. not to say that many such programs, particularly compilers, will not have such
  222. special knowledge. A compiler may be able to produce much better code if it
  223. recognizes such constructs as typecase and multiple-value-bind and gives them
  224. customized treatment.)
  225.  
  226.  
  227.  
  228. An implementation is free to implement as a macro any construct described
  229. herein as a special form. Conversely, an implementation is free to implement as
  230. a special form any construct described herein as a macro if an equivalent macro
  231. definition is also provided. The practical consequence is that the predicates
  232. macro-function and special-form-p may both be true of the same symbol. It is
  233. recommended that a program-analyzing program process a form that is a list
  234. whose car is a symbol as follows:
  235.  
  236.   1.  If the program has particular knowledge about the symbol, process the
  237.      form using special-purpose code. All of the symbols listed in table 5-1
  238.      should fall into this category.
  239.  
  240.   2.  Otherwise, if macro-function is true of the symbol, apply either
  241.      macroexpand or macroexpand-1, as appropriate, to the entire form and then
  242.      start over.
  243.  
  244.   3.  Otherwise, assume it is a function call.
  245.  
  246. -------------------------------------------------------------------------------
  247.  
  248. 5.1.4. Macros
  249.  
  250. If a form is a list and the first element is not the name of a special form, it
  251. may be the name of a macro; if so, the form is said to be a macro call. A macro
  252. is essentially a function from forms to forms that will, given a call to that
  253. macro, compute a new form to be evaluated in place of the macro call. (This
  254. computation is sometimes referred to as macro expansion.) For example, the
  255. macro named return will take a form such as (return x) and from that form
  256. compute a new form (return-from nil x). We say that the old form expands into
  257. the new form. The new form is then evaluated in place of the original form; the
  258. value of the new form is returned as the value of the original form.
  259.  
  260. [change_begin]
  261. X3J13 voted in January 1989 (DOTTED-MACRO-FORMS)   to clarify that macro calls,
  262. and subforms of macro calls, need not be proper lists, but that use of dotted
  263. forms requires the macro definition to use ``. var'' or ``&rest var'' in order
  264. to match them properly. It is then the responsibility of the macro definition
  265. to recognize and appropriately handle such dotted forms or subforms.
  266. [change_end]
  267.  
  268. There are a number of standard macros in Common Lisp, and the user can define
  269. more by using defmacro.
  270.  
  271. Macros provided by a Common Lisp implementation as described herein may expand
  272. into code that is not portable among differing implementations. That is, a
  273. macro call may be implementation-independent because the macro is defined in
  274. this book, but the expansion need not be.
  275.  
  276. -------------------------------------------------------------------------------
  277. Implementation note: Implementors are encouraged to implement the macros
  278. defined in this book, as far as is possible, in such a way that the expansion
  279. will not contain any implementation-dependent special forms, nor contain as
  280. forms data objects that are not considered to be forms in Common Lisp. The
  281. purpose of this restriction is to ensure that the expansion can be processed by
  282. a program-analyzing program in an implementation-independent manner. There is
  283. no problem with a macro expansion containing calls to implementation-dependent
  284. functions. This restriction is not a requirement of Common Lisp; it is
  285. recognized that certain complex macros may be able to expand into significantly
  286. more efficient code in certain implementations by using
  287. implementation-dependent special forms in the macro expansion.
  288. -------------------------------------------------------------------------------
  289.  
  290. 5.1.5. Function Calls
  291.  
  292. If a list is to be evaluated as a form and the first element is not a symbol
  293. that names a special form or macro, then the list is assumed to be a function
  294. call. The first element of the list is taken to name a function. Any and all
  295. remaining elements of the list are forms to be evaluated; one value is obtained
  296. from each form, and these values become the arguments to the function. The
  297. function is then applied to the arguments. The functional computation normally
  298. produces a value, but it may instead call for a non-local exit; see throw. A
  299. function that does return may produce no value or several values; see values.
  300. If and when the function returns, whatever values it returns become the values
  301. of the function-call form.
  302.  
  303. For example, consider the evaluation of the form (+ 3 (* 4 5)). The symbol +
  304. names the addition function, not a special form or macro. Therefore the two
  305. forms 3 and (* 4 5) are evaluated to produce arguments. The form 3 evaluates to
  306. 3, and the form (* 4 5) is a function call (to the multiplication function).
  307. Therefore the forms 4 and 5 are evaluated, producing arguments 4 and 5 for the
  308. multiplication. The multiplication function calculates the number 20 and
  309. returns it. The values 3 and 20 are then given as arguments to the addition
  310. function, which calculates and returns the number 23. Therefore we say (+ 3 (*
  311. 4 5)) => 23.
  312.  
  313. [change_begin]
  314. X3J13 voted in October 1988 (FUNCTION-CALL-EVALUATION-ORDER)   to clarify that
  315. while the arguments in a function call are always evaluated in strict
  316. left-to-right order, whether the function to be called is determined before or
  317. after argument evaluation is unspecified. Programs are in error that rely on a
  318. particular order of evaluation of the first element of a function call relative
  319. to the argument forms.
  320. [change_end]
  321.  
  322. -------------------------------------------------------------------------------
  323.  
  324. 5.2. Functions
  325.  
  326. There are two ways to indicate a function to be used in a function-call form.
  327. One is to use a symbol that names the function. This use of symbols to name
  328. functions is completely independent of their use in naming special and lexical
  329. variables. The other way is to use a lambda-expression, which is a list whose
  330. first element is the symbol lambda. A lambda-expression is not a form; it
  331. cannot be meaningfully evaluated. Lambda-expressions and symbols, when used in
  332. programs as names of functions, can appear only as the first element of a
  333. function-call form, or as the second element of the function special form. Note
  334. that symbols and lambda-expressions are treated as names of functions in these
  335. two contexts. This should be distinguished from the treatment of symbols and
  336. lambda-expressions as function objects, that is, objects that satisfy the
  337. predicate functionp, as when giving such an object to apply or funcall to be
  338. invoked.
  339.  
  340. -------------------------------------------------------------------------------
  341.  
  342.    *  Named Functions
  343.    *  Lambda-Expressions
  344.  
  345. -------------------------------------------------------------------------------
  346.  
  347. 5.2.1. Named Functions
  348.  
  349. A name can be given to a function in one of two ways. A global name can be
  350. given to a function by using the defun construct. A local name can be given to
  351. a function by using the flet or labels special form. When a function is named,
  352. a lambda-expression is effectively associated with that name along with
  353. information about the entities that are lexically apparent at that point. If a
  354. symbol appears as the first element of a function-call form, then it refers to
  355. the definition established by the innermost flet or labels construct that
  356. textually contains the reference, or to the global definition (if any) if there
  357. is no such containing construct.
  358.  
  359. -------------------------------------------------------------------------------
  360.  
  361. 5.2.2. Lambda-Expressions
  362.  
  363. A lambda-expression is a list with the following syntax:
  364.  
  365. (lambda lambda-list . body)
  366.  
  367. The first element must be the symbol lambda. The second element must be a list.
  368. It is called the lambda-list, and specifies names for the parameters of the
  369. function. When the function denoted by the lambda-expression is applied to
  370. arguments, the arguments are matched with the parameters specified by the
  371. lambda-list. The body may then refer to the arguments by using the parameter
  372. names. The body consists of any number of forms (possibly zero). These forms
  373. are evaluated in sequence, and the results of the last form only are returned
  374. as the results of the application (the value nil is returned if there are zero
  375. forms in the body). The complete syntax of a lambda-expression is:
  376.  
  377. (lambda ({var}*
  378.          [&optional {var | (var [initform [svar]])}*]
  379.          [&rest var]
  380.          [&key {var | ({var | (keyword var)} [initform [svar]])}*
  381.                 [&allow-other-keys]]
  382.          [&aux {var | (var [initform])}*)]
  383.    [[{declaration}* | documentation-string]]
  384.    {form}*)
  385.  
  386. Each element of a lambda-list is either a parameter specifier or a lambda-list
  387. keyword; lambda-list keywords begin with &. (Note that lambda-list keywords are
  388. not keywords in the usual sense; they do not belong to the keyword package.
  389. They are ordinary symbols each of whose names begins with an ampersand. This
  390. terminology is unfortunately confusing but is retained for historical reasons.)
  391.  
  392. [old_change_begin]
  393. In all cases a var or svar must be a symbol, the name of a variable; each
  394. keyword must be a keyword symbol, such as :start. An initform may be any form.
  395. [old_change_end]
  396.  
  397. [change_begin]
  398. X3J13 voted in March 1988 (KEYWORD-ARGUMENT-NAME-PACKAGE)   to allow a keyword
  399. in the preceding specification of a lambda-list to be any symbol whatsoever,
  400. not just a keyword symbol in the keyword package. See below.
  401. [change_end]
  402.  
  403. A lambda-list has five parts, any or all of which may be empty:
  404.  
  405.    *  Specifiers for the required parameters. These are all the parameter
  406.      specifiers up to the first lambda-list keyword; if there is no such
  407.      lambda-list keyword, then all the specifiers are for required parameters.
  408.  
  409.    *  Specifiers for optional parameters. If the lambda-list keyword &optional
  410.      is present, the optional parameter specifiers are those following the
  411.      lambda-list keyword &optional up to the next lambda-list keyword or the
  412.      end of the list.
  413.  
  414.    *  A specifier for a rest parameter. The lambda-list keyword &rest, if
  415.      present, must be followed by a single rest parameter specifier, which in
  416.      turn must be followed by another lambda-list keyword or the end of the
  417.      lambda-list.
  418.  
  419.    *  Specifiers for keyword parameters. If the lambda-list keyword &key is
  420.      present, all specifiers up to the next lambda-list keyword or the end of
  421.      the list are keyword parameter specifiers. The keyword parameter
  422.      specifiers may optionally be followed by the lambda-list keyword
  423.      &allow-other-keys.
  424.  
  425.    *  Specifiers for aux variables. These are not really parameters. If the
  426.      lambda-list keyword &key is present, all specifiers after it are auxiliary
  427.      variable specifiers.
  428.  
  429. When the function represented by the lambda-expression is applied to arguments,
  430. the arguments and parameters are processed in order from left to right. In the
  431. simplest case, only required parameters are present in the lambda-list; each is
  432. specified simply by a name var for the parameter variable. When the function is
  433. applied, there must be exactly as many arguments as there are parameters, and
  434. each parameter is bound to one argument. Here, and in general, the parameter is
  435. bound as a lexical variable unless a declaration has been made that it should
  436. be a special binding; see defvar, proclaim, and declare.
  437.  
  438. In the more general case, if there are n required parameters (n may be zero),
  439. there must be at least n arguments, and the required parameters are bound to
  440. the first n arguments. The other parameters are then processed using any
  441. remaining arguments.
  442.  
  443. If optional parameters are specified, then each one is processed as follows. If
  444. any unprocessed arguments remain, then the parameter variable var is bound to
  445. the next remaining argument, just as for a required parameter. If no arguments
  446. remain, however, then the initform part of the parameter specifier is
  447. evaluated, and the parameter variable is bound to the resulting value (or to
  448. nil if no initform appears in the parameter specifier). If another variable
  449. name svar appears in the specifier, it is bound to true if an argument was
  450. available, and to false if no argument remained (and therefore initform had to
  451. be evaluated). The variable svar is called a supplied-p parameter; it is bound
  452. not to an argument but to a value indicating whether or not an argument had
  453. been supplied for another parameter.
  454.  
  455. After all optional parameter specifiers have been processed, then there may or
  456. may not be a rest parameter. If there is a rest parameter, it is bound to a
  457. list of all as-yet-unprocessed arguments. (If no unprocessed arguments remain,
  458. the rest parameter is bound to the empty list.) If there is no rest parameter
  459. and there are no keyword parameters, then there should be no unprocessed
  460. arguments (it is an error if there are).
  461.  
  462. [change_begin]
  463. X3J13 voted in January 1989 (REST-LIST-ALLOCATION)   to clarify that if a
  464. function has a rest parameter and is called using apply, then the list to which
  465. the rest parameter is bound is permitted, but not required, to share top-level
  466. list structure with the list that was the last argument to apply. Programmers
  467. should be careful about performing side effects on the top-level list structure
  468. of a rest parameter.
  469.  
  470. This was the result of a rather long discussion within X3J13 and the wider Lisp
  471. community. To set it in its historical context, I must remark that in Lisp
  472. Machine Lisp the list to which a rest parameter was bound had only dynamic
  473. extent; this in conjunction with the technique of ``cdr-coding'' permitted a
  474. clever stack-allocation technique with very low overhead. However, the early
  475. designers of Common Lisp, after a great deal of debate, concluded that it was
  476. dangerous for cons cells to have dynamic extent; as an example, the ``obvious''
  477. definition of the function list
  478.  
  479. (defun list (&rest x) x)
  480.  
  481. could fail catastrophically. Therefore the first edition simply implied that
  482. the list for a rest parameter, like all other lists, would have indefinite
  483. extent. This still left open the flip side of the question, namely, Is the list
  484. for a rest parameter guaranteed fresh? This is the question addressed by the
  485. X3J13 vote. If it is always freshly consed, then it is permissible to destroy
  486. it, for example by giving it to nconc. However, the requirement always to cons
  487. fresh lists could impose an unacceptable overhead in many implementations. The
  488. clarification approved by X3J13 specifies that the programmer may not rely on
  489. the list being fresh; if the function was called using apply, there is no way
  490. to know where the list came from.
  491. [change_end]
  492.  
  493. Next, any keyword parameters are processed. For this purpose the same arguments
  494. are processed that would be made into a list for a rest parameter. (Indeed, it
  495. is permitted to specify both &rest and &key. In this case the remaining
  496. arguments are used for both purposes; that is, all remaining arguments are made
  497. into a list for the &rest parameter and are also processed for the &key
  498. parameters. This is the only situation in which an argument is used in the
  499. processing of more than one parameter specifier.) If &key is specified, there
  500. must remain an even number of arguments; these are considered as pairs, the
  501. first argument in each pair being interpreted as a keyword name and the second
  502. as the corresponding value.
  503.  
  504. [old_change_begin]
  505. It is an error for the first object of each pair to be anything but a keyword.
  506.  
  507. -------------------------------------------------------------------------------
  508. Rationale: This last restriction is imposed so that a compiler may issue
  509. warnings about certain malformed calls to functions that take keyword
  510. arguments. It must be remembered that the arguments in a function call that
  511. evaluate to keywords are just like any other arguments and may be any evaluable
  512. forms. A compiler could not, without additional context, issue a warning about
  513. the call
  514.  
  515. (fill seq item x y)
  516.  
  517. because in principle the variable x might have as its value a keyword such as
  518. :start. However, a compiler would be justified in issuing a warning about the
  519. call
  520.  
  521. (fill seq item 0 10)
  522.  
  523. because the constant 0 is definitely not a keyword. Similarly, if in the first
  524. case the variable x had been declared to be of type integer, then type analysis
  525. could enable the compiler to justify a warning.
  526. -------------------------------------------------------------------------------
  527. [old_change_end]
  528.  
  529. [change_begin]
  530. X3J13 voted in March 1988 (KEYWORD-ARGUMENT-NAME-PACKAGE)   to allow a keyword
  531. in a lambda-list to be any symbol whatsoever, not just a keyword symbol in the
  532. keyword package. If, after &key, a variable appears alone or within only one
  533. set of parentheses (possibly with an initform and a svar), then the behavior is
  534. as before: a keyword symbol with the same name as the variable is used as the
  535. keyword-name when matching arguments to parameter specifiers. Only a parameter
  536. specifier of the form ((keyword var) ...) can cause the keyword-name not to be
  537. a keyword symbol, by specifying a symbol not in the keyword package as the
  538. keyword. For example:
  539.  
  540. (defun wager (&key ((secret password) nil) amount)
  541.   (format nil "You ~A $~D"
  542.           (if (eq password 'joe-sent-me) "win" "lose")
  543.           amount))
  544.  
  545. (wager :amount 100) => "You lose $100"
  546. (wager :amount 100 'secret 'joe-sent-me) => "You win $100"
  547.  
  548. The secret word could be made even more secret in this example by placing it in
  549. some other obscure package, so that one would have to write
  550.  
  551. (wager :amount 100 'obscure:secret 'joe-sent-me) => "You win $100"
  552.  
  553. to win anything.
  554. [change_end]
  555.  
  556. In each keyword parameter specifier must be a name var for the parameter
  557. variable. If an explicit keyword is specified, then that is the keyword name
  558. for the parameter. Otherwise the name var serves to indicate the keyword name,
  559. in that a keyword with the same name (in the keyword package) is used as the
  560. keyword. Thus
  561.  
  562. (defun foo (&key radix (type 'integer)) ...)
  563.  
  564. means exactly the same as
  565.  
  566. (defun foo (&key ((:radix radix)) ((:type type) 'integer)) ...)
  567.  
  568. The keyword parameter specifiers are, like all parameter specifiers,
  569. effectively processed from left to right. For each keyword parameter specifier,
  570. if there is an argument pair whose keyword name matches that specifier's
  571. keyword name (that is, the names are eq), then the parameter variable for that
  572. specifier is bound to the second item (the value) of that argument pair. If
  573. more than one such argument pair matches, it is not an error; the leftmost
  574. argument pair is used. If no such argument pair exists, then the initform for
  575. that specifier is evaluated and the parameter variable is bound to that value
  576. (or to nil if no initform was specified). The variable svar is treated as for
  577. ordinary optional parameters: it is bound to true if there was a matching
  578. argument pair, and to false otherwise.
  579.  
  580. It is an error if an argument pair has a keyword name not matched by any
  581. parameter specifier, unless at least one of the following two conditions is
  582. met:
  583.  
  584.    *  &allow-other-keys was specified in the lambda-list.
  585.  
  586.    *  Somewhere among the keyword argument pairs is a pair whose keyword is
  587.      :allow-other-keys and whose value is not nil.
  588.  
  589. If either condition obtains, then it is not an error for an argument pair to
  590. match no parameter specified, and the argument pair is simply ignored (but such
  591. an argument pair is accessible through the &rest parameter if one was
  592. specified). The purpose of these mechanisms is to allow sharing of argument
  593. lists among several functions and to allow either the caller or the called
  594. function to specify that such sharing may be taking place.
  595.  
  596. After all parameter specifiers have been processed, the auxiliary variable
  597. specifiers (those following the lambda-list keyword &aux) are processed from
  598. left to right. For each one, the initform is evaluated and the variable var
  599. bound to that value (or to nil if no initform was specified). Nothing can be
  600. done with &aux variables that cannot be done with the special form let*:
  601.  
  602. (lambda (x y &aux (a (car x)) (b 2) c) ...)
  603.    == (lambda (x y) (let* ((a (car x)) (b 2) c) ...))
  604.  
  605. Which to use is purely a matter of style.
  606.  
  607. Whenever any initform is evaluated for any parameter specifier, that form may
  608. refer to any parameter variable to the left of the specifier in which the
  609. initform appears, including any supplied-p variables, and may rely on the fact
  610. that no other parameter variable has yet been bound (including its own
  611. parameter variable).
  612.  
  613. Once the lambda-list has been processed, the forms in the body of the
  614. lambda-expression are executed. These forms may refer to the arguments to the
  615. function by using the names of the parameters. On exit from the function,
  616. either by a normal return of the function's value(s) or by a non-local exit,
  617. the parameter bindings, whether lexical or special, are no longer in effect.
  618. (The bindings are not necessarily permanently discarded, for a lexical binding
  619. can later be reinstated if a ``closure'' over that binding was created, perhaps
  620. by using function, and saved before the exit occurred.)
  621.  
  622. Examples of &optional and &rest parameters:
  623.  
  624. ((lambda (a b) (+ a (* b 3))) 4 5) => 19
  625. ((lambda (a &optional (b 2)) (+ a (* b 3))) 4 5) => 19
  626. ((lambda (a &optional (b 2)) (+ a (* b 3))) 4) => 10
  627. ((lambda (&optional (a 2 b) (c 3 d) &rest x) (list a b c d x)))
  628.    => (2 nil 3 nil nil)
  629. ((lambda (&optional (a 2 b) (c 3 d) &rest x) (list a b c d x))
  630.  6)
  631.    => (6 t 3 nil nil)
  632. ((lambda (&optional (a 2 b) (c 3 d) &rest x) (list a b c d x))
  633.  6 3)
  634.    => (6 t 3 t nil)
  635. ((lambda (&optional (a 2 b) (c 3 d) &rest x) (list a b c d x))
  636.  6 3 8)
  637.    => (6 t 3 t (8))
  638. ((lambda (&optional (a 2 b) (c 3 d) &rest x) (list a b c d x))
  639.  6 3 8 9 10 11)
  640.    => (6 t 3 t (8 9 10 11))
  641.  
  642. Examples of &key parameters:
  643.  
  644. ((lambda (a b &key c d) (list a b c d)) 1 2)
  645.    => (1 2 nil nil)
  646. ((lambda (a b &key c d) (list a b c d)) 1 2 :c 6)
  647.    => (1 2 6 nil)
  648. ((lambda (a b &key c d) (list a b c d)) 1 2 :d 8)
  649.    => (1 2 nil 8)
  650. ((lambda (a b &key c d) (list a b c d)) 1 2 :c 6 :d 8)
  651.    => (1 2 6 8)
  652. ((lambda (a b &key c d) (list a b c d)) 1 2 :d 8 :c 6)
  653.    => (1 2 6 8)
  654. ((lambda (a b &key c d) (list a b c d)) :a 1 :d 8 :c 6)
  655.    => (:a 1 6 8)
  656. ((lambda (a b &key c d) (list a b c d)) :a :b :c :d)
  657.    => (:a :b :d nil)
  658.  
  659. Examples of mixtures:
  660.  
  661. ((lambda (a &optional (b 3) &rest x &key c (d a))
  662.    (list a b c d x))
  663.  1)   => (1 3 nil 1 ())
  664.  
  665. ((lambda (a &optional (b 3) &rest x &key c (d a))
  666.    (list a b c d x))
  667.  1 2)   => (1 2 nil 1 ())
  668.  
  669. ((lambda (a &optional (b 3) &rest x &key c (d a))
  670.    (list a b c d x))
  671.  :c 7)   => (:c 7 nil :c ())
  672.  
  673. ((lambda (a &optional (b 3) &rest x &key c (d a))
  674.    (list a b c d x))
  675.  1 6 :c 7)   => (1 6 7 1 (:c 7))
  676.  
  677. ((lambda (a &optional (b 3) &rest x &key c (d a))
  678.    (list a b c d x))
  679.  1 6 :d 8)   => (1 6 nil 8 (:d 8))
  680.  
  681. ((lambda (a &optional (b 3) &rest x &key c (d a))
  682.    (list a b c d x))
  683.  1 6 :d 8 :c 9 :d 10)   => (1 6 9 8 (:d 8 :c 9 :d 10))
  684.  
  685. All lambda-list keywords are permitted, but not terribly useful, in
  686. lambda-expressions appearing explicitly as the first element of a function-call
  687. form. They are extremely useful, however, in functions given global names by
  688. defun.
  689.  
  690. All symbols whose names begin with & are conventionally reserved for use as
  691. lambda-list keywords and should not be used as variable names. Implementations
  692. of Common Lisp are free to provide additional lambda-list keywords.
  693.  
  694. [Constant]
  695. lambda-list-keywords
  696.  
  697. The value of lambda-list-keywords is a list of all the lambda-list keywords
  698. used in the implementation, including the additional ones used only by
  699. defmacro. This list must contain at least the symbols &optional, &rest, &key,
  700. &allow-other-keys, &aux, &body, &whole, and &environment.
  701.  
  702. As an example of the use of &allow-other-keys and :allow-other-keys, consider a
  703. function that takes two keyword arguments of its own and also accepts
  704. additional keyword arguments to be passed to make-array:
  705.  
  706. (defun array-of-strings (str dims &rest keyword-pairs
  707.                          &key (start 0) end &allow-other-keys)
  708.   (apply #'make-array dims
  709.          :initial-element (subseq str start end)
  710.          :allow-other-keys t
  711.          keyword-pairs))
  712.  
  713. This function takes a string and dimensioning information and returns an array
  714. of the specified dimensions, each of whose elements is the specified string.
  715. However, :start and :end keyword arguments may be used in the usual manner (see
  716. chapter 14) to specify that a substring of the given string should be used. In
  717. addition, the presence of &allow-other-keys in the lambda-list indicates that
  718. the caller may specify additional keyword arguments; the &rest argument
  719. provides access to them. These additional keyword arguments are fed to
  720. make-array. Now, make-array normally does not allow the keywords :start and
  721. :end to be used, and it would be an error to specify such keyword arguments to
  722. make-array. However, the presence in the call to make-array of the keyword
  723. argument :allow-other-keys with a non-nil value causes any extraneous keyword
  724. arguments, including :start and :end, to be acceptable and ignored.
  725.  
  726. [Constant]
  727. lambda-parameters-limit
  728.  
  729. The value of lambda-parameters-limit is a positive integer that is the upper
  730. exclusive bound on the number of distinct parameter names that may appear in a
  731. single lambda-list. This bound depends on the implementation but will not be
  732. smaller than 50. Implementors are encouraged to make this limit as large as
  733. practicable without sacrificing performance. See call-arguments-limit.
  734.  
  735. -------------------------------------------------------------------------------
  736.  
  737. 5.3. Top-Level Forms
  738.  
  739. The standard way for the user to interact with a Common Lisp implementation is
  740. via a read-eval-print loop: the system repeatedly reads a form from some input
  741. source (such as a keyboard or a disk file), evaluates it, and then prints the
  742. value(s) to some output sink (such as a display screen or another disk file).
  743. Any form (evaluable data object) is acceptable; however, certain special forms
  744. are specifically designed to be convenient for use as top-level forms, rather
  745. than as forms embedded within other forms in the way that (+ 3 4) is embedded
  746. within (if p (+ 3 4) 6). These top-level special forms may be used to define
  747. globally named functions, to define macros, to make declarations, and to define
  748. global values for special variables.
  749.  
  750. [old_change_begin]
  751. It is not illegal to use these forms at other than top level, but whether it is
  752. meaningful to do so depends on context. Compilers, for example, may not
  753. recognize these forms properly in other than top-level contexts. (As a special
  754. case, however, if a progn form appears at top level, then all forms within that
  755. progn are considered by the compiler to be top-level forms.)
  756. [old_change_end]
  757.  
  758. [change_begin]
  759. X3J13 voted in March 1989 (DEFINING-MACROS-NON-TOP-LEVEL)   to clarify that,
  760. while defining forms normally appear at top level, it is meaningful to place
  761. them in non-top-level contexts. All defining forms that create functional
  762. objects from code appearing as argument forms must ensure that such argument
  763. forms refer to the enclosing lexical environment. Compilers must handle
  764. defining forms properly in all situations, not just top-level contexts.
  765. However, certain compile-time side effects of these defining forms are
  766. performed only when the defining forms occur at top level (see section 25.1).
  767. [change_end]
  768.  
  769. -------------------------------------------------------------------------------
  770. Compatibility note: In MacLisp, a top-level progn is considered to contain
  771. top-level forms only if the first form is (quote compile). This odd marker is
  772. unnecessary in Common Lisp.
  773. -------------------------------------------------------------------------------
  774.  
  775. Macros are usually defined by using the special form defmacro. This facility is
  776. fairly complicated; it is described in chapter 8.
  777.  
  778. -------------------------------------------------------------------------------
  779.  
  780.    *  Defining Named Functions
  781.    *  Declaring Global Variables and Named Constants
  782.    *  Control of Time of Evaluation
  783.  
  784. -------------------------------------------------------------------------------
  785.  
  786. 5.3.1. Defining Named Functions
  787.  
  788. The defun special form is the usual means of defining named functions.
  789.  
  790. [Macro]
  791. defun name lambda-list [[ {declaration}* | doc-string ]] {form}*
  792.  
  793. Evaluating a defun form causes the symbol name to be a global name for the
  794. function specified by the lambda-expression
  795.  
  796. (lambda lambda-list {declaration | doc-string}* {form}*)
  797.  
  798. defined in the lexical environment in which the defun form was executed.
  799. Because defun forms normally appear at top level, this is normally the null
  800. lexical environment.
  801.  
  802. [change_begin]
  803. X3J13 voted in March 1989 (DEFINING-MACROS-NON-TOP-LEVEL)   to clarify that,
  804. while defining forms normally appear at top level, it is meaningful to place
  805. them in non-top-level contexts; defun must define the function within the
  806. enclosing lexical environment, not within the null lexical environment.
  807.  
  808. X3J13 voted in March 1989 (FUNCTION-NAME)   to extend defun to accept any
  809. function-name (a symbol or a list whose car is setf - see section 7.1) as a
  810. name. Thus one may write
  811.  
  812. (defun (setf cadr) ...)
  813.  
  814. to define a setf expansion function for cadr (although it may be much more
  815. convenient to use defsetf or define-modify-macro).
  816. [change_end]
  817.  
  818. If the optional documentation string doc-string is present, then it is attached
  819. to the name as a documentation string of type function; see documentation. If
  820. doc-string is not followed by a declaration, it may be present only if at least
  821. one form is also specified, as it is otherwise taken to be a form. It is an
  822. error if more than one doc-string is present.
  823.  
  824. The forms constitute the body of the defined function; they are executed as an
  825. implicit progn.
  826.  
  827. The body of the defined function is implicitly enclosed in a block construct
  828. whose name is the same as the name of the function. Therefore return-from may
  829. be used to exit from the function.
  830.  
  831. Other implementation-dependent bookkeeping actions may be taken as well by
  832. defun. The name is returned as the value of the defun form. For example:
  833.  
  834. (defun discriminant (a b c)
  835.   (declare (number a b c))
  836.   "Compute the discriminant for a quadratic equation.
  837.    Given a, b, and c, the value b^2-4*a*c is calculated.
  838.    The quadratic equation a*x^2+b*x+c=0 has real, multiple,
  839.    or complex roots depending on whether this calculated
  840.    value is positive, zero, or negative, respectively."
  841.   (- (* b b) (* 4 a c)))
  842.    => discriminant
  843.    and now (discriminant 1 2/3 -2) => 76/9
  844.  
  845. [change_begin]
  846. The documentation string in this example neglects to mention that the
  847. coefficients a, b, and c must be real for the discrimination criterion to hold.
  848. Here is an improved version:
  849.  
  850.   "Compute the discriminant for a quadratic equation.
  851.    Given a, b, and c, the value b^2-4*a*c is calculated.
  852.    If the coefficients a, b, and c are all real (that is,
  853.    not complex), then the quadratic equation a*x^2+b*x+c=0
  854.    has real, multiple, or complex roots depending on
  855.    whether this calculated value is positive, zero, or
  856.    negative, respectively."
  857. [change_end]
  858.  
  859. It is permissible to use defun to redefine a function, to install a corrected
  860. version of an incorrect definition, for example. It is permissible to redefine
  861. a macro as a function. It is an error to attempt to redefine the name of a
  862. special form (see table 5-1) as a function.
  863.  
  864. -------------------------------------------------------------------------------
  865.  
  866. 5.3.2. Declaring Global Variables and Named Constants
  867.  
  868. The defvar and defparameter special forms are the usual means of specifying
  869. globally defined variables. The defconstant special form is used for defining
  870. named constants.
  871.  
  872. [Macro]
  873. defvar name [initial-value [documentation]]
  874. defparameter name initial-value [documentation]
  875. defconstant name initial-value [documentation]
  876.  
  877. defvar is the recommended way to declare the use of a special variable in a
  878. program.
  879.  
  880. (defvar variable)
  881.  
  882. proclaims variable to be special (see proclaim), and may perform other
  883. system-dependent bookkeeping actions.
  884.  
  885. [change_begin]
  886. X3J13 voted in June 1987 (DEFVAR-INITIALIZATION)   to clarify that if no
  887. initial-value form is provided, defvar does not change the value of the
  888. variable; if no initial-value form is provided and the variable has no value,
  889. defvar does not give it a value.
  890. [change_end]
  891.  
  892. If a second argument form is supplied,
  893.  
  894. (defvar variable initial-value)
  895.  
  896. then variable is initialized to the result of evaluating the form initial-value
  897. unless it already has a value. The initial-value form is not evaluated unless
  898. it is used; this fact is useful if evaluation of the initial-value form does
  899. something expensive like creating a large data structure.
  900.  
  901. [change_begin]
  902. X3J13 voted in June 1987 (DEFVAR-INIT-TIME)   to clarify that evaluation of the
  903. initial-value and the initialization of the variable occur, if at all, at the
  904. time the defvar form is executed, and that the initial-value form is evaluated
  905. if and only if the variable does not already have a value.
  906. [change_end]
  907.  
  908. The initialization is performed by assignment and thus assigns a global value
  909. to the variable unless there are currently special bindings of that variable.
  910. Normally there should not be any such special bindings.
  911.  
  912. defvar also provides a good place to put a comment describing the meaning of
  913. the variable, whereas an ordinary special proclamation offers the temptation to
  914. declare several variables at once and not have room to describe them all.
  915.  
  916. (defvar *visible-windows* 0
  917.   "Number of windows at least partially visible on the screen")
  918.  
  919. defparameter is similar to defvar, but defparameter requires an initial-value
  920. form, always evaluates the form, and assigns the result to the variable. The
  921. semantic distinction is that defvar is intended to declare a variable changed
  922. by the program, whereas defparameter is intended to declare a variable that is
  923. normally constant but can be changed (possibly at run time), where such a
  924. change is considered a change to the program. defparameter therefore does not
  925. indicate that the quantity never changes; in particular, it does not license
  926. the compiler to build assumptions about the value into programs being compiled.
  927.  
  928. defconstant is like defparameter but does assert that the value of the variable
  929. name is fixed and does license the compiler to build assumptions about the
  930. value into programs being compiled. (However, if the compiler chooses to
  931. replace references to the name of the constant by the value of the constant in
  932. code to be compiled, perhaps in order to allow further optimization, the
  933. compiler must take care that such ``copies'' appear to be eql to the object
  934. that is the actual value of the constant. For example, the compiler may freely
  935. make copies of numbers but must exercise care when the value is a list.)
  936.  
  937. It is an error if there are any special bindings of the variable at the time
  938. the defconstant form is executed (but implementations may or may not check for
  939. this).
  940.  
  941. Once a name has been declared by defconstant to be constant, any further
  942. assignment to or binding of that special variable is an error. This is the case
  943. for such system-supplied constants as t and most-positive-fixnum. A compiler
  944. may also choose to issue warnings about bindings of the lexical variable of the
  945. same name.
  946.  
  947. [change_begin]
  948. X3J13 voted in January 1989 (DEFCONSTANT-SPECIAL)   to clarify the preceding
  949. paragraph by specifying that it is an error to rebind constant symbols as
  950. either lexical or special variables. Consequently, a valid reference to a
  951. symbol declared with defconstant always refers to its global value.
  952. (Unfortunately, this violates the principle of referential transparency, for
  953. one cannot always choose names for lexical variables without regard to
  954. surrounding context.)
  955. [change_end]
  956.  
  957. For any of these constructs, the documentation should be a string. The string
  958. is attached to the name of the variable, parameter, or constant under the
  959. variable documentation type; see the documentation function.
  960.  
  961. [change_begin]
  962. X3J13 voted in March 1988 (DEFVAR-DOCUMENTATION)   to clarify that the
  963. documentation-string is not evaluated but must appear as a literal string when
  964. the defvar, defparameter, or defconstant form is evaluated.
  965.  
  966. For example, the form
  967.  
  968. (defvar *avoid-registers* nil "Compilation control switch #43")
  969.  
  970. is legitimate, but
  971.  
  972. (defvar *avoid-registers* nil
  973.   (format nil "Compilation control switch #~D"
  974.           (incf *compiler-switch-number*)))
  975.  
  976. is erroneous because the call to format is not a literal string.
  977.  
  978. (On the other hand, the form
  979.  
  980. (defvar *avoid-registers* nil
  981.   #.(format nil "Compilation control switch #~D"
  982.             (incf *compiler-switch-number*)))
  983.  
  984. might be used to accomplish the same purpose, because the call to format is
  985. evaluated at read time; when the defvar form is evaluated, only the result of
  986. the call to format, a string, appears in the defvar form.)
  987. [change_end]
  988.  
  989. These constructs are normally used only as top-level forms. The value returned
  990. by each of these constructs is the name declared.
  991.  
  992. -------------------------------------------------------------------------------
  993.  
  994. 5.3.3. Control of Time of Evaluation
  995.  
  996. [old_change_begin]
  997. The eval-when special form allows pieces of code to be executed only at compile
  998. time, only at load time, or when interpreted but not compiled. Its uses are
  999. relatively esoteric.
  1000.  
  1001. [Special Form]
  1002. eval-when ({situation}*) {form}*
  1003.  
  1004. The body of an eval-when form is processed as an implicit progn, but only in
  1005. the situations listed. Each situation must be a symbol, either compile, load,
  1006. or eval.
  1007.  
  1008. eval specifies that the interpreter should process the body. compile specifies
  1009. that the compiler should evaluate the body at compile time in the compilation
  1010. context. load specifies that the compiler should arrange to evaluate the forms
  1011. in the body when the compiled file containing the eval-when form is loaded.
  1012.  
  1013. The eval-when construct may be more precisely understood in terms of a model of
  1014. how the compiler processes forms in a file to be compiled. Successive forms are
  1015. read from the file using the function read. These top-level forms are normally
  1016. processed in what we shall call not-compile-time mode. There is another mode
  1017. called compile-time-too mode. The eval-when special form controls which of
  1018. these two modes to use.
  1019.  
  1020. Every form is processed as follows:
  1021.  
  1022.    *  If the form is an eval-when form:
  1023.  
  1024.         o  If the situation load is specified:
  1025.  
  1026.              +  If the situation compile is specified, or if the current
  1027.                processing mode is compile-time-too and the situation eval is
  1028.                specified, then process each of the forms in the body in
  1029.                compile-time-too mode.
  1030.  
  1031.              +  Otherwise, process each of the forms in the body in
  1032.                not-compile-time mode.
  1033.  
  1034.         o  If the situation load is not specified:
  1035.  
  1036.              +  If the situation compile is specified, or if the current
  1037.                processing mode is compile-time-too and the situation eval is
  1038.                specified, then evaluate each of the forms in the body in the
  1039.                compiler's executing environment.
  1040.  
  1041.              +  Otherwise, ignore the eval-when form entirely.
  1042.  
  1043.    *  If the form is not an eval-when form, then do two things. First, if the
  1044.      current processing mode is compile-time-too mode, evaluate the form in the
  1045.      compiler's executing environment. Second, perform normal compiler
  1046.      processing of the form (compiling functions defined by defun forms, and so
  1047.      on).
  1048.  
  1049. One example of the use of eval-when is that if the compiler is to be able to
  1050. properly read a file that uses user-defined reader macro characters, it is
  1051. necessary to write
  1052.  
  1053. (eval-when (compile load eval)
  1054.   (set-macro-character #\$ #'(lambda (stream char)
  1055.                                (declare (ignore char))
  1056.                                (list 'dollar (read stream)))))
  1057.  
  1058. This causes the call to set-macro-character to be executed in the compiler's
  1059. execution environment, thereby modifying its reader syntax table.
  1060. [old_change_end]
  1061.  
  1062. [change_begin]
  1063. X3J13 voted in March 1989 (EVAL-WHEN-NON-TOP-LEVEL)   to completely redesign
  1064. the eval-when construct to solve some problems concerning its treatment in
  1065. other than top-level contexts. The new definition is upward compatible with the
  1066. old definition, but the old keywords are deprecated.
  1067.  
  1068. [Special Form]
  1069. eval-when ({situation}*) {form}*
  1070.  
  1071. The body of an eval-when form is processed as an implicit progn, but only in
  1072. the situations listed. Each situation must be a symbol, either
  1073. :compile-toplevel, :load-toplevel, or :execute.
  1074.  
  1075. The use of :compile-toplevel and :load-toplevel controls whether and when
  1076. processing occurs for top-level forms. The use of :execute controls whether
  1077. processing occurs for non-top-level forms.
  1078.  
  1079. The eval-when construct may be more precisely understood in terms of a model of
  1080. how the file compiler, compile-file, processes forms in a file to be compiled.
  1081.  
  1082. Successive forms are read from the file by the file compiler using read. These
  1083. top-level forms are normally processed in what we call ``not-compile-time''
  1084. mode. There is one other mode, called ``compile-time-too'' mode, which can come
  1085. into play for top-level forms. The eval-when special form is used to annotate a
  1086. program in a way that allows the program doing the processing to select the
  1087. appropriate mode.
  1088.  
  1089. Processing of top-level forms in the file compiler works as follows:
  1090.  
  1091.    *  If the form is a macro call, it is expanded and the result is processed
  1092.      as a top-level form in the same processing mode (compile-time-too or
  1093.      not-compile-time).
  1094.  
  1095.    *  If the form is a progn (or locally (LOCALLY-TOP-LEVEL)   ) form, each of
  1096.      its body forms is sequentially processed as top-level forms in the same
  1097.      processing mode.
  1098.  
  1099.    *  If the form is a compiler-let, macrolet, or symbol-macrolet, the file
  1100.      compiler makes the appropriate bindings and recursively processes the body
  1101.      forms as an implicit top-level progn with those bindings in effect, in the
  1102.      same processing mode.
  1103.  
  1104.    *  If the form is an eval-when form, it is handled according to the
  1105.      following table:
  1106.  
  1107.  
  1108.  
  1109.      In the preceding table the column LT asks whether :load-toplevel is one of
  1110.      the situations specified in the eval-when form; CT similarly refers to
  1111.      :compile-toplevel and EX to :execute. The column CTTM asks whether the
  1112.      eval-when form was encountered while in compile-time-too mode. The phrase
  1113.      ``process body'' means to process the body as an implicit top-level progn
  1114.      in the indicated mode, and ``evaluate body'' means to evaluate the body
  1115.      forms sequentially as an implicit progn in the dynamic execution context
  1116.      of the compiler and in the lexical environment in which the eval-when
  1117.      appears.
  1118.  
  1119.    *  Otherwise, the form is a top-level form that is not one of the special
  1120.      cases. If in compile-time-too mode, the compiler first evaluates the form
  1121.      and then performs normal compiler processing on it. If in not-compile-time
  1122.      mode, only normal compiler processing is performed (see section 25.1). Any
  1123.      subforms are treated as non-top-level forms.
  1124.  
  1125. Note that top-level forms are guaranteed to be processed in the order in which
  1126. they textually appear in the file, and that each top-level form read by the
  1127. compiler is processed before the next is read. However, the order of processing
  1128. (including, in particular, macro expansion) of subforms that are not top-level
  1129. forms is unspecified.
  1130.  
  1131. For an eval-when form that is not a top-level form in the file compiler (that
  1132. is, either in the interpreter, in compile, or in the file compiler but not at
  1133. top level), if the :execute situation is specified, its body is treated as an
  1134. implicit progn. Otherwise, the body is ignored and the eval-when form has the
  1135. value nil.
  1136.  
  1137. For the sake of backward compatibility, a situation may also be compile, load,
  1138. or eval. Within a top-level eval-when form these have the same meaning as
  1139. :compile-toplevel, :load-toplevel, and :execute, respectively; but their effect
  1140. is undefined when used in an eval-when form that is not at top level.
  1141.  
  1142. The following effects are logical consequences of the preceding specification:
  1143.  
  1144.    *  It is never the case that the execution of a single eval-when expression
  1145.      will execute the body code more than once.
  1146.  
  1147.    *  The old keyword eval was a misnomer because execution of the body need
  1148.      not be done by eval. For example, when the function definition
  1149.  
  1150.           (defun foo () (eval-when (:execute) (print 'foo)))
  1151.  
  1152.  
  1153.      is compiled the call to print should be compiled, not evaluated at compile
  1154.      time.
  1155.  
  1156.    *  Macros intended for use in top-level forms should arrange for all
  1157.      side-effects to be done by the forms in the macro expansion. The
  1158.      macro-expander itself should not perform the side-effects.
  1159.  
  1160.      (defmacro foo ()
  1161.        (really-foo)                              ;Wrong
  1162.        `(really-foo))
  1163.  
  1164.      (defmacro foo ()
  1165.        `(eval-when (:compile-toplevel
  1166.                     :load-toplevel :execute)     ;Right
  1167.          (really-foo)))
  1168.  
  1169.      Adherence to this convention will mean that such macros will behave
  1170.      intuitively when called in non-top-level positions.
  1171.  
  1172.    *  Placing a variable binding around an eval-when reliably captures the
  1173.      binding because the ``compile-time-too'' mode cannot occur (because the
  1174.      eval-when could not be a top-level form). For example,
  1175.  
  1176.      (let ((x 3))
  1177.        (eval-when (:compile-toplevel :load-toplevel :execute)
  1178.          (print x)))
  1179.  
  1180.      will print 3 at execution (that is, load) time and will not print anything
  1181.      at compile time. This is important so that expansions of defun and
  1182.      defmacro can be done in terms of eval-when and can correctly capture the
  1183.      lexical environment. For example, an implementation might expand a defun
  1184.      form such as
  1185.  
  1186.      (defun bar (x) (defun foo () (+ x 3)))
  1187.  
  1188.      into
  1189.  
  1190.      (progn (eval-when (:compile-toplevel)
  1191.               (compiler::notice-function 'bar '(x)))
  1192.             (eval-when (:load-toplevel :execute)
  1193.               (setf (symbol-function 'bar)
  1194.                     #'(lambda (x)
  1195.                         (progn (eval-when (:compile-toplevel)
  1196.                                  (compiler::notice-function 'foo
  1197.                                                             '()))
  1198.                                (eval-when (:load-toplevel :execute)
  1199.                                  (setf (symbol-function 'foo)
  1200.                                        #'(lambda () (+ x 3)))))))))
  1201.  
  1202.      which by the preceding rules would be treated the same as
  1203.  
  1204.      (progn (eval-when (:compile-toplevel)
  1205.               (compiler::notice-function 'bar '(x)))
  1206.             (eval-when (:load-toplevel :execute)
  1207.               (setf (symbol-function 'bar)
  1208.                     #'(lambda (x)
  1209.                         (progn (eval-when (:load-toplevel :execute)
  1210.                                  (setf (symbol-function 'foo)
  1211.                                        #'(lambda () (+ x 3)))))))))
  1212.  
  1213. Here are some additional examples.
  1214.  
  1215. (let ((x 1))
  1216.   (eval-when (:execute :load-toplevel :compile-toplevel)
  1217.     (setf (symbol-function 'foo1) #'(lambda () x))))
  1218.  
  1219. The eval-when in the preceding expression is not at top level, so only the
  1220. :execute keyword is considered. At compile time, this has no effect. At load
  1221. time (if the let is at top level), or at execution time (if the let is embedded
  1222. in some other form which does not execute until later), this sets
  1223. (symbol-function 'foo1) to a function that returns 1.
  1224.  
  1225. (eval-when (:execute :load-toplevel :compile-toplevel)
  1226.   (let ((x 2))
  1227.     (eval-when (:execute :load-toplevel :compile-toplevel)
  1228.       (setf (symbol-function 'foo2) #'(lambda () x)))))
  1229.  
  1230. If the preceding expression occurs at the top level of a file to be compiled,
  1231. it has both a compile time and a load-time effect of setting (symbol-function
  1232. 'foo2) to a function that returns 2.
  1233.  
  1234. (eval-when (:execute :load-toplevel :compile-toplevel)
  1235.   (setf (symbol-function 'foo3) #'(lambda () 3)))
  1236.  
  1237. If the preceding expression occurs at the top level of a file to be compiled,
  1238. it has both a compile time and a load-time effect of setting the function cell
  1239. of foo3 to a function that returns 3.
  1240.  
  1241. (eval-when (:compile-toplevel)
  1242.   (eval-when (:compile-toplevel)
  1243.     (print 'foo4)))
  1244.  
  1245. The preceding expression always does nothing; it simply returns nil.
  1246.  
  1247. (eval-when (:compile-toplevel)
  1248.   (eval-when (:execute)
  1249.     (print 'foo5)))
  1250.  
  1251. If the preceding form occurs at the top level of a file to be compiled, foo5 is
  1252. printed at compile time. If this form occurs in a non-top-level position,
  1253. nothing is printed at compile time. Regardless of context, nothing is ever
  1254. printed at load time or execution time.
  1255.  
  1256. (eval-when (:execute :load-toplevel)
  1257.   (eval-when (:compile-toplevel)
  1258.     (print 'foo6)))
  1259.  
  1260. If the preceding form occurs at the top level of a file to be compiled, foo6 is
  1261. printed at compile time. If this form occurs in a non-top-level position,
  1262. nothing is printed at compile time. Regardless of context, nothing is ever
  1263. printed at load time or execution time.
  1264.  
  1265. [change_end]
  1266.  
  1267. -------------------------------------------------------------------------------
  1268.  
  1269.  
  1270.  
  1271.  
  1272.  
  1273.  
  1274.  
  1275.  
  1276.